Workflow Nodes

Workflow nodes represent individual execution operations within a BindAI workflow. A node can perform an operation, evaluate information, control execution flow, or coordinate another component of the application. BindAI V1 supports nodes for sequential execution, agents, tools, conditions, loops, parallel execution, joins, and human tasks. The term node describes the role an operation plays in a workflow. It should not be interpreted as a specific public WorkflowNode class unless that class is exposed by the current BindAI implementation.

What Is a Workflow Node?

A workflow node represents one operation within a larger execution process. Conceptually:

Input
  |
  v
Node
  |
  v
Output

A complete workflow combines multiple operations:

Node A
  |
  v
Node B
  |
  v
Node C

The workflow controls how execution moves between those operations.

Workflow Graph

A workflow can be represented as a graph of connected operations. A simple process is:

Start
  |
  v
Agent
  |
  v
Tool
  |
  v
End

A conditional process can branch:

              +--> Branch A
              |
Node A -------+
              |
              +--> Branch B

A parallel process can execute independent operations:

              +--> Agent A --+
              |              |
Start --------+--> Tool B ----+--> Join --> Continue
              |              |
              +--> Agent C --+

The workflow execution layer determines how these operations are coordinated.

Supported V1 Node Types

BindAI V1 supports these workflow node types:

Node	Purpose
Start	Entry point of a workflow
End	Completion point of a workflow
Agent	Executes an agent
Tool	Executes a registered tool
Condition	Selects an execution path
Loop	Repeats execution based on a condition
Parallel	Starts independent branches
Join	Synchronizes parallel branches
Human Task	Pauses execution for human input

These nodes can be combined to create executable workflow graphs.

Start Node

The Start node represents the beginning of a workflow.

Start
  |
  v
Next Node

It does not perform an application operation itself. It provides the entry point for workflow execution.

End Node

The End node represents the completion of a workflow path.

Previous Node
     |
     v
    End

A workflow can contain different paths that eventually reach an End node.

Agent Node

The Agent node executes a configured BindAI agent.

Workflow
   |
   v
Agent
   |
   v
Agent Output
   |
   v
Next Node

An Agent node can consume workflow input and store its output in a workflow variable. For example:

input
  |
  v
Agent
  |
  v
agent_output

The resulting value can then be passed to another node.

Agent Input Mapping

Agent nodes can use workflow variables as input. For example:

customer_message
       |
       v
     Agent
       |
       v
   agent_output

Multiple workflow values can also be mapped into the agent input. This allows a workflow to explicitly control which values are provided to an agent.

Tool Node

The Tool node executes a registered BindAI tool.

Workflow
   |
   v
Tool
   |
   v
ToolResult
   |
   v
Next Node

Tools perform executable application operations. A tool result contains information about whether the operation succeeded and its resulting value or error. Conceptually:

ToolResult
├── success
├── value
└── error

Tool Parameter Mapping

Tool nodes can map workflow variables into tool parameters. For example:

agent_output
     |
     v
Tool
     |
     +--> text
     |
     v
tool_output

This allows the output of one workflow operation to become the input of another.

Agent and Tool Nodes Together

Agent and Tool nodes can be combined:

Start
  |
  v
Agent
  |
  v
Tool
  |
  v
End

For example, an agent can determine a value and a tool can perform a deterministic operation using that value. This separates reasoning from application execution.

Condition Node

The Condition node controls which workflow path executes next.

             +--> True Path
             |
Input --> Condition
             |
             +--> False Path

A condition evaluates an expression using workflow state. For example:

Agent
  |
  v
Condition
 /        \
true      false
 |          |
 v          v
Continue   End

Conditions are useful for:

Validation
Routing
Approval decisions
Result-based branching
Workflow control

Condition Expressions

A condition is configured with an expression that determines the selected path. Conceptually:

Workflow State
      |
      v
Condition Expression
      |
   +--+--+
   |     |
 true  false

The expression should be based on values available during workflow execution. The exact expression syntax should follow the configured BindAI workflow implementation.

Loop Node

The Loop node allows workflow execution to repeat based on a condition. Conceptually:

Process
   |
   v
Loop Condition
 /       \
more     done
 |         |
 v         v
Repeat    Continue
 |
 +----> Process

Loops are useful for:

Processing collections
Repeated operations
Iterative workflows
Processing items until a condition is satisfied

A loop should always have a clear termination condition.

Parallel Node

The Parallel node starts independent workflow branches.

             +--> Agent A --+
             |              |
Start --> Parallel           +--> Join
             |              |
             +--> Agent B --+

Parallel execution is useful when branches do not depend on one another. Examples include:

Independent agent execution
Independent tool operations
Separate analysis tasks
Independent workflow branches

Join Node

The Join node provides the synchronization point after parallel branches.

             +--> Branch A --+
             |               |
Parallel ---+--> Branch B ---+--> Join --> Next
             |               |
             +--> Branch C --+

The Join node allows the workflow to continue after the parallel branches have completed. Parallel and Join nodes are therefore normally used together:

Parallel
   |
   +--> Branch A
   |
   +--> Branch B
   |
   v
 Join
   |
   v
Next Node

Human Task Node

The Human Task node pauses workflow execution until a human action is provided.

Agent
  |
  v
Human Task
  |
  v
Waiting
  |
  v
Human Action
  |
  v
Continue

A Human Task can represent an approval or rejection decision. For example:

Human Task
   |
   +--> approved --> Continue
   |
   +--> rejected --> Alternative Path

Human Tasks are useful for:

Approval workflows
Content review
Sensitive actions
Manual verification
Human-in-the-loop decisions

Human Task Persistence

When a Human Task is waiting, the workflow instance can remain persisted. Conceptually:

Workflow
   |
   v
Human Task
   |
   v
Waiting
   |
   +---- persisted instance
   |
   v
Human Action
   |
   v
Resume

This allows the workflow to pause and later continue without requiring the original execution request to remain active.

Node Execution State

Workflow execution maintains state while moving between nodes. Conceptually:

Node A
  |
  v
Workflow State
  |
  v
Node B
  |
  v
Updated State

State can contain:

Input values
Agent outputs
Tool results
Intermediate application data
Execution information
Human-task information

Passing Results Between Nodes

Results produced by one node can be consumed by later nodes. For example:

Agent
  |
  v
agent_output
  |
  v
Tool
  |
  v
tool_output
  |
  v
Condition

This creates an explicit data flow through the workflow. Workflow variables provide the mechanism for carrying these values between operations.

Node Context

Workflow operations execute within workflow execution state. Conceptually:

Workflow Execution
       |
       v
    Context
       |
       +--> Variables
       +--> Metadata
       +--> Execution State

The exact context API depends on the BindAI workflow implementation. Documentation should not invent a specific node context API unless it is part of the verified public API.

Connection-Backed Tool Nodes

Connections can participate in workflows through connection-backed tools. The architecture is:

Connection
    |
    v
Connection-backed Tool
    |
    v
Tool Node
    |
    v
External Service

In BindAI V1, the implemented Studio connection provider is Webhook. For example:

Start
  |
  v
Agent
  |
  v
Webhook Tool
  |
  v
External Webhook
  |
  v
End

This provides a real workflow execution path to an external HTTP endpoint.

Memory and Nodes

Agents executed through workflow nodes can use configured Memory. For example:

Workflow
   |
   v
Agent Node
   |
   +--> Memory
   |
   v
Tool Node

Memory provides retained information for agent interactions. Memory is separate from workflow state:

Workflow state supports workflow execution.
Memory provides retained agent or application information.

Knowledge and Nodes

Agents executed through workflow nodes can also use configured Knowledge. For example:

Workflow
   |
   v
Agent Node
   |
   +--> Knowledge
   |
   v
Tool Node

Knowledge provides searchable information that can be used during agent execution.

Node Connections

Connections determine where execution proceeds. A sequential graph is:

Node A
  |
  v
Node B
  |
  v
Node C

A branching graph is:

              +--> Node B
              |
Node A -------+
              |
              +--> Node C

A parallel graph is:

              +--> Node B --+
              |             |
Node A -------+--> Node C --+--> Node D
              |             |
              +--> Node E --+

The workflow runtime interprets these relationships during execution.

Node Independence

Well-designed workflow nodes should remain focused. A good node generally:

Has one clear responsibility
Reads only the information it needs
Produces a clear result
Updates state predictably
Avoids unnecessary coupling

Small, focused operations are easier to test and maintain.

Node Failure

Individual nodes can fail during workflow execution. For example:

Workflow
   |
   +--> Agent Failure
   |
   +--> Tool Failure
   |
   +--> Connection Failure
   |
   +--> Invalid Condition

The resulting workflow behavior depends on the node and workflow configuration. For V1, failure handling should be implemented explicitly through the available workflow structure rather than assuming advanced retry or timeout policies.

Conditional Failure Handling

A workflow can use conditions to route based on available execution values. For example:

Tool
  |
  v
Condition
 /        \
success   failure
 |           |
 v           v
Continue   Human Task

This allows applications to define explicit failure paths using the workflow primitives available in V1.

Custom Workflow Operations

Applications may need domain-specific behavior. That behavior should generally be implemented as an appropriate BindAI component, such as an agent or tool, and then composed into the workflow. For example:

Workflow
   |
   +--> Agent
   |
   +--> Tool
   |
   +--> Condition
   |
   +--> Human Task

Developers should not assume that BindAI exposes a public base class named:

WorkflowNode

unless that class exists in the installed version. Concrete workflow APIs should always be documented from the actual implementation.

Node Connections and Data Flow

Workflow structure and data flow are related but distinct. The graph determines execution order:

Agent
  |
  v
Tool
  |
  v
End

Workflow variables determine what data moves between those operations:

input
  |
  v
Agent
  |
  v
agent_output
  |
  v
Tool
  |
  v
tool_output

Together, graph structure and workflow state define the executable process.

Visual Node Construction

BindAI Studio provides a visual editor for constructing workflow nodes and their connections. The editor supports:

Adding workflow nodes
Positioning nodes
Connecting nodes
Configuring node properties
Saving workflow definitions
Loading saved workflow definitions

The resulting workflow definition can be loaded by the runtime. This means the visual graph represents an executable workflow rather than only a design diagram.

Testing Workflow Nodes

Node behavior should be tested both individually where appropriate and as part of complete workflows. Important V1 cases include:

Agent execution
Tool execution
Condition true path
Condition false path
Loop termination
Parallel execution
Join synchronization
Human-task approval
Human-task rejection
Connection-backed tool execution
Workflow persistence
Node failure handling

Testing should verify actual runtime behavior rather than only the visual representation of the graph.

API Accuracy

This documentation intentionally does not assume public classes such as:

StartNode
EndNode
AgentNode
ToolNode
ConditionNode
LoopNode
ParallelNode
JoinNode
HumanTaskNode
WorkflowNode

Likewise, methods such as:

.add_node(...)
.connect(...)
.start_node(...)
.end_node(...)
.build(...)

should not be treated as BindAI APIs unless they are verified in the current implementation. When a concrete node API is exposed, documentation should provide:

The actual import path.
The actual constructor or factory.
The actual parameters.
The actual execution behavior.
Tests demonstrating the behavior.

This keeps workflow documentation synchronized with the implementation.

Best Practices

When designing workflow nodes:

Give each node one clear responsibility.
Keep reasoning and deterministic execution separate.
Pass data through explicit workflow variables.
Keep conditions simple and readable.
Give loops clear termination conditions.
Use parallel execution only for independent work.
Use Join nodes to synchronize parallel branches.
Use Human Tasks for explicit human decisions.
Keep external operations behind tools or connection-backed tools.
Avoid unnecessary coupling between nodes.
Define important failure paths explicitly.
Test successful and failure paths.
Document concrete APIs only after implementation verification.

Current BindAI V1 Scope

The current BindAI workflow node foundation supports:

Start nodes
End nodes
Agent nodes
Tool nodes
Condition nodes
Loop nodes
Parallel nodes
Join nodes
Human Task nodes
Workflow variables
Workflow state
Persistent workflow execution state in Studio
Connection-backed tools
Webhook connections
Agent Memory
Agent Knowledge
Visual workflow construction
Studio API execution

These capabilities form the executable workflow foundation of BindAI V1.

Deferred Workflow Features

The following workflow features are outside the current V1 scope:

Advanced retry policies
Advanced timeout policies
Workflow scheduling
Automation triggers
Distributed workflow execution
Advanced workflow monitoring
Additional external connection providers
Advanced Memory administration
Advanced Knowledge administration
MCP management

These should only be documented as implemented capabilities after they are actually available and verified.

Summary

Workflow nodes represent the individual operations that make up a BindAI workflow. BindAI V1 provides nodes for:

Start
  |
  v
Agent
  |
  v
Tool
  |
  v
Condition
 /       \
true     false
 |         |
 v         v
Parallel  Human Task
   |
   v
 Join
   |
   v
 End

Nodes can coordinate agents, tools, workflow state, Memory, Knowledge, human decisions, and configured Connections. The key principle is:

A workflow coordinates operations; each node should remain focused on its own responsibility.

Specific node classes and builder methods should only be documented when they are part of the verified public BindAI API.

​Workflow Nodes

​What Is a Workflow Node?

​Workflow Graph

​Supported V1 Node Types

​Start Node

​End Node

​Agent Node

​Agent Input Mapping

​Tool Node

​Tool Parameter Mapping

​Agent and Tool Nodes Together

​Condition Node

​Condition Expressions

​Loop Node

​Parallel Node

​Join Node

​Human Task Node

​Human Task Persistence

​Node Execution State

​Passing Results Between Nodes

​Node Context

​Connection-Backed Tool Nodes

​Memory and Nodes

​Knowledge and Nodes

​Node Connections

​Node Independence

​Node Failure

​Conditional Failure Handling

​Custom Workflow Operations

​Node Connections and Data Flow

​Visual Node Construction

​Testing Workflow Nodes

​API Accuracy

​Best Practices

​Current BindAI V1 Scope

​Deferred Workflow Features

​Summary